<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>RESTful API 最佳实践 | 皮卡车</title>
    <meta name="description" content="皮卡车的文档, vuepress 文档">
    <meta name="generator" content="VuePress 1.3.1">
    <link rel="apple-touch-icon" href="/apple-touch-icon.png">
  <link rel="icon" href="/favicon.ico">
  <link rel="manifest" href="/manifest.json">
  <meta name="theme-color" content="#ffffff">
  <meta name="google-site-verification" content="Ld_AEWr30siza2LmmZ12csitRGsSj9gqqEAch0UXkTc">
    
    <link rel="preload" href="/assets/css/0.styles.1a6a4f51.css" as="style"><link rel="preload" href="/assets/js/app.1f0f93c9.js" as="script"><link rel="preload" href="/assets/js/2.f28f3227.js" as="script"><link rel="preload" href="/assets/js/83.81ad8dbf.js" as="script"><link rel="preload" href="/assets/js/4.494c614b.js" as="script"><link rel="preload" href="/assets/js/3.a7eaa85f.js" as="script"><link rel="prefetch" href="/assets/js/10.7b76d38f.js"><link rel="prefetch" href="/assets/js/100.0d62a3f6.js"><link rel="prefetch" href="/assets/js/101.4916ac0c.js"><link rel="prefetch" href="/assets/js/102.0ee21f66.js"><link rel="prefetch" href="/assets/js/103.872c594c.js"><link rel="prefetch" href="/assets/js/104.0bff815e.js"><link rel="prefetch" href="/assets/js/105.46330c43.js"><link rel="prefetch" href="/assets/js/106.4ad211ca.js"><link rel="prefetch" href="/assets/js/107.d9011871.js"><link rel="prefetch" href="/assets/js/108.bab8ed0e.js"><link rel="prefetch" href="/assets/js/109.b7e4a790.js"><link rel="prefetch" href="/assets/js/11.518e0dbb.js"><link rel="prefetch" href="/assets/js/110.1eb492e8.js"><link rel="prefetch" href="/assets/js/111.ee6a2e31.js"><link rel="prefetch" href="/assets/js/112.05d655c6.js"><link rel="prefetch" href="/assets/js/113.0a4cf8f0.js"><link rel="prefetch" href="/assets/js/114.ef783947.js"><link rel="prefetch" href="/assets/js/115.11bbdb9c.js"><link rel="prefetch" href="/assets/js/116.5646126d.js"><link rel="prefetch" href="/assets/js/117.854d26bf.js"><link rel="prefetch" href="/assets/js/118.1e514b13.js"><link rel="prefetch" href="/assets/js/119.aa944f45.js"><link rel="prefetch" href="/assets/js/12.511e3547.js"><link rel="prefetch" href="/assets/js/120.1c6f450c.js"><link rel="prefetch" href="/assets/js/121.44f16ee6.js"><link rel="prefetch" href="/assets/js/122.f877b8e8.js"><link rel="prefetch" href="/assets/js/123.0563fdd5.js"><link rel="prefetch" href="/assets/js/124.4cd97316.js"><link rel="prefetch" href="/assets/js/125.a502f4ee.js"><link rel="prefetch" href="/assets/js/126.c7e94093.js"><link rel="prefetch" href="/assets/js/127.bd8aed7f.js"><link rel="prefetch" href="/assets/js/128.66063cc3.js"><link rel="prefetch" href="/assets/js/129.21bb1073.js"><link rel="prefetch" href="/assets/js/13.9e5bee4e.js"><link rel="prefetch" href="/assets/js/130.c8edfccb.js"><link rel="prefetch" href="/assets/js/131.7a1f29be.js"><link rel="prefetch" href="/assets/js/132.f589fc06.js"><link rel="prefetch" href="/assets/js/133.55ac5c9a.js"><link rel="prefetch" href="/assets/js/134.eeab127b.js"><link rel="prefetch" href="/assets/js/135.5a1571dd.js"><link rel="prefetch" href="/assets/js/136.b72b4d1c.js"><link rel="prefetch" href="/assets/js/137.678e022a.js"><link rel="prefetch" href="/assets/js/138.ba4108fa.js"><link rel="prefetch" href="/assets/js/139.0b02b599.js"><link rel="prefetch" href="/assets/js/14.b9ec07e6.js"><link rel="prefetch" href="/assets/js/140.690e4e4c.js"><link rel="prefetch" href="/assets/js/141.709da4ed.js"><link rel="prefetch" href="/assets/js/142.f2de76c0.js"><link rel="prefetch" href="/assets/js/143.4dcb17f0.js"><link rel="prefetch" href="/assets/js/144.730ef429.js"><link rel="prefetch" href="/assets/js/145.d881c754.js"><link rel="prefetch" href="/assets/js/146.f3379a41.js"><link rel="prefetch" href="/assets/js/147.eeb9ca6f.js"><link rel="prefetch" href="/assets/js/148.bb6020cd.js"><link rel="prefetch" href="/assets/js/149.1d34dea6.js"><link rel="prefetch" href="/assets/js/15.d0fa1a9d.js"><link rel="prefetch" href="/assets/js/150.599238ba.js"><link rel="prefetch" href="/assets/js/151.9655268f.js"><link rel="prefetch" href="/assets/js/152.1f843fa4.js"><link rel="prefetch" href="/assets/js/153.7af45ca6.js"><link rel="prefetch" href="/assets/js/154.eff93a56.js"><link rel="prefetch" href="/assets/js/155.ff07fba4.js"><link rel="prefetch" href="/assets/js/156.1b1814b7.js"><link rel="prefetch" href="/assets/js/157.8ac4c21b.js"><link rel="prefetch" href="/assets/js/158.aa8a0124.js"><link rel="prefetch" href="/assets/js/159.d61fdb37.js"><link rel="prefetch" href="/assets/js/16.ccd2bd60.js"><link rel="prefetch" href="/assets/js/17.ddc8fde4.js"><link rel="prefetch" href="/assets/js/18.a06e60cc.js"><link rel="prefetch" href="/assets/js/19.64b3dec9.js"><link rel="prefetch" href="/assets/js/20.3615e182.js"><link rel="prefetch" href="/assets/js/21.0c654d53.js"><link rel="prefetch" href="/assets/js/22.720aac8f.js"><link rel="prefetch" href="/assets/js/23.0dc53b91.js"><link rel="prefetch" href="/assets/js/24.d4b75b0e.js"><link rel="prefetch" href="/assets/js/25.9120702e.js"><link rel="prefetch" href="/assets/js/26.b24d89e2.js"><link rel="prefetch" href="/assets/js/27.55df94ab.js"><link rel="prefetch" href="/assets/js/28.250c68a5.js"><link rel="prefetch" href="/assets/js/29.75a3c8f3.js"><link rel="prefetch" href="/assets/js/30.8cdc2fcd.js"><link rel="prefetch" href="/assets/js/31.45303d68.js"><link rel="prefetch" href="/assets/js/32.f4225739.js"><link rel="prefetch" href="/assets/js/33.15b21267.js"><link rel="prefetch" href="/assets/js/34.5baca30b.js"><link rel="prefetch" href="/assets/js/35.5d9dfab1.js"><link rel="prefetch" href="/assets/js/36.981eadca.js"><link rel="prefetch" href="/assets/js/37.cead7f6b.js"><link rel="prefetch" href="/assets/js/38.ee6bcaf1.js"><link rel="prefetch" href="/assets/js/39.e7579788.js"><link rel="prefetch" href="/assets/js/40.01d2b30b.js"><link rel="prefetch" href="/assets/js/41.19cf06ce.js"><link rel="prefetch" href="/assets/js/42.15941cde.js"><link rel="prefetch" href="/assets/js/43.66adb73c.js"><link rel="prefetch" href="/assets/js/44.8d99ed62.js"><link rel="prefetch" href="/assets/js/45.12ea9159.js"><link rel="prefetch" href="/assets/js/46.644efa88.js"><link rel="prefetch" href="/assets/js/47.531131c7.js"><link rel="prefetch" href="/assets/js/48.b214f000.js"><link rel="prefetch" href="/assets/js/49.e42d4b72.js"><link rel="prefetch" href="/assets/js/5.7e277dc8.js"><link rel="prefetch" href="/assets/js/50.de0aa85c.js"><link rel="prefetch" href="/assets/js/51.8be2974c.js"><link rel="prefetch" href="/assets/js/52.cc067888.js"><link rel="prefetch" href="/assets/js/53.4ceb2c6b.js"><link rel="prefetch" href="/assets/js/54.b2647058.js"><link rel="prefetch" href="/assets/js/55.dc3df953.js"><link rel="prefetch" href="/assets/js/56.921a6934.js"><link rel="prefetch" href="/assets/js/57.1e24b1fd.js"><link rel="prefetch" href="/assets/js/58.f4e8ebac.js"><link rel="prefetch" href="/assets/js/59.17ab117b.js"><link rel="prefetch" href="/assets/js/6.4014218f.js"><link rel="prefetch" href="/assets/js/60.352cea9b.js"><link rel="prefetch" href="/assets/js/61.77289388.js"><link rel="prefetch" href="/assets/js/62.ec0ed919.js"><link rel="prefetch" href="/assets/js/63.c75dcb25.js"><link rel="prefetch" href="/assets/js/64.59d15a75.js"><link rel="prefetch" href="/assets/js/65.7e5a14bb.js"><link rel="prefetch" href="/assets/js/66.4e770ba1.js"><link rel="prefetch" href="/assets/js/67.0742f21a.js"><link rel="prefetch" href="/assets/js/68.a6ed34fd.js"><link rel="prefetch" href="/assets/js/69.48c9a47f.js"><link rel="prefetch" href="/assets/js/7.c5ecd7d3.js"><link rel="prefetch" href="/assets/js/70.eb477192.js"><link rel="prefetch" href="/assets/js/71.1be57009.js"><link rel="prefetch" href="/assets/js/72.6859561c.js"><link rel="prefetch" href="/assets/js/73.aae65018.js"><link rel="prefetch" href="/assets/js/74.59d76d34.js"><link rel="prefetch" href="/assets/js/75.04e23427.js"><link rel="prefetch" href="/assets/js/76.74d6eb6a.js"><link rel="prefetch" href="/assets/js/77.fba76057.js"><link rel="prefetch" href="/assets/js/78.0da94b25.js"><link rel="prefetch" href="/assets/js/79.14676976.js"><link rel="prefetch" href="/assets/js/8.08c85334.js"><link rel="prefetch" href="/assets/js/80.7494721f.js"><link rel="prefetch" href="/assets/js/81.f04f6229.js"><link rel="prefetch" href="/assets/js/82.e4c6f74b.js"><link rel="prefetch" href="/assets/js/84.d28e4a3d.js"><link rel="prefetch" href="/assets/js/85.d99fa7fa.js"><link rel="prefetch" href="/assets/js/86.597ecadb.js"><link rel="prefetch" href="/assets/js/87.e6d21734.js"><link rel="prefetch" href="/assets/js/88.b43a52d4.js"><link rel="prefetch" href="/assets/js/89.a5ba287d.js"><link rel="prefetch" href="/assets/js/9.658cd6b3.js"><link rel="prefetch" href="/assets/js/90.c253df12.js"><link rel="prefetch" href="/assets/js/91.8946a93d.js"><link rel="prefetch" href="/assets/js/92.8b8f1ae0.js"><link rel="prefetch" href="/assets/js/93.aa73c784.js"><link rel="prefetch" href="/assets/js/94.9326bcc7.js"><link rel="prefetch" href="/assets/js/95.46b64b79.js"><link rel="prefetch" href="/assets/js/96.61a9b0b9.js"><link rel="prefetch" href="/assets/js/97.65a03aad.js"><link rel="prefetch" href="/assets/js/98.7aa56ed0.js"><link rel="prefetch" href="/assets/js/99.a652c8d5.js">
    <link rel="stylesheet" href="/assets/css/0.styles.1a6a4f51.css">
  </head>
  <body>
    <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/" class="home-link router-link-active"><!----> <span class="site-name">皮卡车</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/" class="nav-link">
  Home
</a></div><div class="nav-item"><a href="/guide/" class="nav-link">
  Guide
</a></div><div class="nav-item"><a href="/computer/" class="nav-link">
  计算机
</a></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="系统" class="dropdown-title"><span class="title">系统</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/os/linux/" class="nav-link">
  Linux
</a></li><li class="dropdown-item"><!----> <a href="/os/manjaro/" class="nav-link">
  Manjaro
</a></li><li class="dropdown-item"><!----> <a href="/os/ubuntu/" class="nav-link">
  Ubuntu
</a></li><li class="dropdown-item"><!----> <a href="/os/centos/" class="nav-link">
  CentOS
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="前端" class="dropdown-title"><span class="title">前端</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/frontend/javascript/" class="nav-link">
  JavaScript
</a></li><li class="dropdown-item"><!----> <a href="https://css.shanyuhai.top/" target="_blank" rel="noopener noreferrer" class="nav-link external">
  CSS
  <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li><li class="dropdown-item"><!----> <a href="/frontend/webpack/" class="nav-link">
  Webpack
</a></li><li class="dropdown-item"><!----> <a href="/frontend/d3js/" class="nav-link">
  D3
</a></li><li class="dropdown-item"><!----> <a href="/frontend/utils/" class="nav-link">
  Utils
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="后端" class="dropdown-title"><span class="title">后端</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/backend/nodejs/" class="nav-link">
  Nodejs
</a></li><li class="dropdown-item"><!----> <a href="/backend/koa/" class="nav-link">
  Koa
</a></li><li class="dropdown-item"><!----> <a href="/backend/mongodb/" class="nav-link">
  MongoDB
</a></li><li class="dropdown-item"><!----> <a href="/backend/nginx/" class="nav-link">
  Nginx
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="开发工具" class="dropdown-title"><span class="title">开发工具</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/tools/git/" class="nav-link">
  Git
</a></li><li class="dropdown-item"><!----> <a href="/tools/github/" class="nav-link">
  Github
</a></li><li class="dropdown-item"><!----> <a href="/tools/vscode/" class="nav-link">
  VSCode
</a></li><li class="dropdown-item"><!----> <a href="/tools/chrome/" class="nav-link">
  Chrome Developer tools
</a></li><li class="dropdown-item"><!----> <a href="/tools/bookmark-scripts/" class="nav-link">
  Bookmark scripts
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="更多" class="dropdown-title"><span class="title">更多</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/more/algorithm/" class="nav-link">
  算法
</a></li><li class="dropdown-item"><!----> <a href="/more/interview/" class="nav-link">
  面试题
</a></li><li class="dropdown-item"><!----> <a href="/more/hodgepodge/" class="nav-link router-link-active">
  大杂烩
</a></li><li class="dropdown-item"><!----> <a href="/more/clean/" class="nav-link">
  风格指南
</a></li><li class="dropdown-item"><!----> <a href="https://v1.vuepress.vuejs.org/zh/" target="_blank" rel="noopener noreferrer" class="nav-link external">
  VuePress1.x 官网
  <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li></ul></div></div> <!----></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/" class="nav-link">
  Home
</a></div><div class="nav-item"><a href="/guide/" class="nav-link">
  Guide
</a></div><div class="nav-item"><a href="/computer/" class="nav-link">
  计算机
</a></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="系统" class="dropdown-title"><span class="title">系统</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/os/linux/" class="nav-link">
  Linux
</a></li><li class="dropdown-item"><!----> <a href="/os/manjaro/" class="nav-link">
  Manjaro
</a></li><li class="dropdown-item"><!----> <a href="/os/ubuntu/" class="nav-link">
  Ubuntu
</a></li><li class="dropdown-item"><!----> <a href="/os/centos/" class="nav-link">
  CentOS
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="前端" class="dropdown-title"><span class="title">前端</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/frontend/javascript/" class="nav-link">
  JavaScript
</a></li><li class="dropdown-item"><!----> <a href="https://css.shanyuhai.top/" target="_blank" rel="noopener noreferrer" class="nav-link external">
  CSS
  <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li><li class="dropdown-item"><!----> <a href="/frontend/webpack/" class="nav-link">
  Webpack
</a></li><li class="dropdown-item"><!----> <a href="/frontend/d3js/" class="nav-link">
  D3
</a></li><li class="dropdown-item"><!----> <a href="/frontend/utils/" class="nav-link">
  Utils
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="后端" class="dropdown-title"><span class="title">后端</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/backend/nodejs/" class="nav-link">
  Nodejs
</a></li><li class="dropdown-item"><!----> <a href="/backend/koa/" class="nav-link">
  Koa
</a></li><li class="dropdown-item"><!----> <a href="/backend/mongodb/" class="nav-link">
  MongoDB
</a></li><li class="dropdown-item"><!----> <a href="/backend/nginx/" class="nav-link">
  Nginx
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="开发工具" class="dropdown-title"><span class="title">开发工具</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/tools/git/" class="nav-link">
  Git
</a></li><li class="dropdown-item"><!----> <a href="/tools/github/" class="nav-link">
  Github
</a></li><li class="dropdown-item"><!----> <a href="/tools/vscode/" class="nav-link">
  VSCode
</a></li><li class="dropdown-item"><!----> <a href="/tools/chrome/" class="nav-link">
  Chrome Developer tools
</a></li><li class="dropdown-item"><!----> <a href="/tools/bookmark-scripts/" class="nav-link">
  Bookmark scripts
</a></li></ul></div></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="更多" class="dropdown-title"><span class="title">更多</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/more/algorithm/" class="nav-link">
  算法
</a></li><li class="dropdown-item"><!----> <a href="/more/interview/" class="nav-link">
  面试题
</a></li><li class="dropdown-item"><!----> <a href="/more/hodgepodge/" class="nav-link router-link-active">
  大杂烩
</a></li><li class="dropdown-item"><!----> <a href="/more/clean/" class="nav-link">
  风格指南
</a></li><li class="dropdown-item"><!----> <a href="https://v1.vuepress.vuejs.org/zh/" target="_blank" rel="noopener noreferrer" class="nav-link external">
  VuePress1.x 官网
  <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li></ul></div></div> <!----></nav>  <ul class="sidebar-links"><li><section class="sidebar-group depth-0"><p class="sidebar-heading open"><span>HODGEPODGE</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/more/hodgepodge/" class="sidebar-link">首页</a></li><li><a href="/more/hodgepodge/maybe-optimization-is-needed.html" class="sidebar-link">可能需要优化的 JavaScript 代码</a></li><li><a href="/more/hodgepodge/mpv-keyboards.html" class="sidebar-link">mpv 快捷键</a></li><li><a href="/more/hodgepodge/restful-api-best-practices.html" class="active sidebar-link">RESTful API 最佳实践</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/more/hodgepodge/restful-api-best-practices.html#介绍" class="sidebar-link">介绍</a></li><li class="sidebar-sub-header"><a href="/more/hodgepodge/restful-api-best-practices.html#url-设计" class="sidebar-link">URL 设计</a></li><li class="sidebar-sub-header"><a href="/more/hodgepodge/restful-api-best-practices.html#状态码" class="sidebar-link">状态码</a></li><li class="sidebar-sub-header"><a href="/more/hodgepodge/restful-api-best-practices.html#服务器响应" class="sidebar-link">服务器响应</a></li><li class="sidebar-sub-header"><a href="/more/hodgepodge/restful-api-best-practices.html#参考资料" class="sidebar-link">参考资料</a></li></ul></li><li><a href="/more/hodgepodge/you-get.html" class="sidebar-link">You Get</a></li></ul></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h2 id="介绍"><a href="#介绍" class="header-anchor">#</a> 介绍</h2> <p>RESTful（Representational State Transfer）是一种 API 设计规范，用于 Web 数据接口的设计。</p> <p>如果一个架构符合 REST 原则，就称之为 RESTful 架构。</p> <blockquote><p><strong>要理解 RESTful 架构，最好的方法就是去理解 Representational State Transfer 这个词组到底是什么意思，它的每一个词代表了什么涵义。</strong></p></blockquote> <p>REST的名称&quot;表现层状态转化&quot;中，省略了主语。&quot;表现层&quot;其实指的是&quot;资源&quot;（Resources）的&quot;表现层&quot;。</p> <p><strong>所谓&quot;资源&quot;，就是网络上的一个实体，或者说是网络上的一个具体信息。</strong></p> <p>一般会使用一个 URI（Universal Resource Identifier，统一资源标志符）来指向它。</p> <blockquote><p>参考资料中的描述存在一些问题，当对一些问题产生疑惑时推荐通过谷歌或者 <a href="https://zh.wikipedia.org/wiki/%E7%BB%9F%E4%B8%80%E8%B5%84%E6%BA%90%E6%A0%87%E5%BF%97%E7%AC%A6" target="_blank" rel="noopener noreferrer">wiki<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a> 来查询。</p> <p>原本 URI 包含 URL 和 URN，但是很遗憾 URN 使用率过低，导致目前几乎所有的 URI 都是 URL。</p></blockquote> <h2 id="url-设计"><a href="#url-设计" class="header-anchor">#</a> URL 设计</h2> <div class="custom-block warning"><p class="custom-block-title">WARNING</p> <p>此处设计仅作为一个思路，个人觉得直接参阅大公司的 API 设计指南更好一些。</p> <ol><li><a href="https://cloud.google.com/apis/design/" target="_blank" rel="noopener noreferrer">Google<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li> <li><a href="https://developer.github.com/v3/" target="_blank" rel="noopener noreferrer">Github<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li> <li><a href="https://developer.twitter.com/en/docs/basics/getting-started" target="_blank" rel="noopener noreferrer">Twitter<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></li> <li><a href="https://docs.microsoft.com/zh-cn/azure/architecture/best-practices/api-design" target="_blank" rel="noopener noreferrer">Microsoft<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a> <span class="badge error" style="vertical-align:top;" data-v-15b7b770>中文友好</span></li></ol></div> <h3 id="_1-动词-宾语"><a href="#_1-动词-宾语" class="header-anchor">#</a> 1. 动词 + 宾语</h3> <p>RESTful 的核心思想就是，客户端发出的数据操作指令都是 “动词 + 宾语” 的结构。比如 <code>GET /articles</code> 这个命令，<code>GET</code> 是动词，<code>articles</code> 是宾语。</p> <p>动词通常为五种 HTTP 方法，对应 CRUD 操作：</p> <ul><li>GET：读取（READ）；</li> <li>POST：新建（Create）；</li> <li>PUT：更新（Update）；</li> <li>PATCH：更新（Update），通常是部分更新；</li> <li>DELETE：删除（Delete）。</li></ul> <h3 id="_2-动词的覆盖"><a href="#_2-动词的覆盖" class="header-anchor">#</a> 2. 动词的覆盖</h3> <p>某些情况只能使用 <code>GET</code> 和 <code>POST</code> 方法。此时可以采用 <code>X-HTTP-Method-Override</code> 来模拟操作。</p> <h3 id="_3-宾语必须是名词"><a href="#_3-宾语必须是名词" class="header-anchor">#</a> 3. 宾语必须是名词</h3> <p>宾语是 HTTP 动作的对象，它应该是名词。</p> <h3 id="_4-复数-url"><a href="#_4-复数-url" class="header-anchor">#</a> 4. 复数 URL</h3> <p>既然 URL 是名词，那么应该使用复数，还是单数呢？</p> <p>此处建议都使用复数 URL，如 <code>GET /articles/2</code> 。</p> <h3 id="_5-避免多级-url"><a href="#_5-避免多级-url" class="header-anchor">#</a> 5. 避免多级 URL</h3> <p>常见的情况是，资源需要多级分类，因此很容易写出多级的 URL，比如获取某个作者的某一类文章。</p> <div class="language-bash extra-class"><pre class="language-bash"><code><span class="token comment"># 缺乏语义及难以扩展</span>
GET /authors/12/categories/2

<span class="token comment"># 更好的做法是，除了第一级，其他级别都用查询字符串表达</span>
GET /authors/12?categories<span class="token operator">=</span><span class="token number">2</span>

<span class="token comment"># 查询已发布的文章</span>
GET /articles?published<span class="token operator">=</span>true
</code></pre></div><h2 id="状态码"><a href="#状态码" class="header-anchor">#</a> 状态码</h2> <h3 id="_1-状态码必须精确"><a href="#_1-状态码必须精确" class="header-anchor">#</a> 1. 状态码必须精确</h3> <p>客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。</p> <p>HTTP 状态码就是一个三位数，分成五个类别：</p> <ul><li>1xx：相关信息；</li> <li>2xx：操作成功；</li> <li>3xx：重定向；</li> <li>4xx：客户端错误；</li> <li>5xx：服务器错误。</li></ul> <p>这五大类共包含 100 多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都是标准的（或约定的）解释，客户端只需要查看状态码，就可以判断发生了什么情况，所以服务器应该返回尽可能精确的状态码。</p> <p>API 不需要 <code>1xx</code> 状态码。</p> <h3 id="_2-2xx-状态码"><a href="#_2-2xx-状态码" class="header-anchor">#</a> 2. <code>2xx</code> 状态码</h3> <p><code>200</code> 状态码表示操作成功，但是不同的方法可以返回更精确的状态码：</p> <ul><li>GET：200 OK；</li> <li>POST：201 Created；</li> <li>PUT：200 OK；</li> <li>PATCH：200 OK；</li> <li>DELETE：204 No Content;</li></ul> <p>上面代码中，<code>POST</code> 返回 <code>201</code> 状态码，表示已经生成了新的资源；<code>DELETE</code> 状态码返回 <code>204</code> 状态码，表示资源已经不存在。</p> <p>此外，<code>202 Accepted</code> 状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作。举个例子：</p> <div class="language-http extra-class"><pre class="language-http"><code><span class="token response-status">HTTP/1.1 <span class="token property">202 Accepted</span></span>

{
  &quot;task&quot;: {
    &quot;href&quot;: &quot;/api/company/job-management/jobs/2130040&quot;,
    &quot;id&quot;: &quot;2130040&quot;
  }
}
</code></pre></div><h3 id="_3-3xx-状态码"><a href="#_3-3xx-状态码" class="header-anchor">#</a> 3. <code>3xx</code> 状态码</h3> <p>API 用不到 <code>301</code> 状态码（永久重定向）和 <code>302</code> 状态码（暂时重定向，<code>307</code> 也是这个含义），因为它们可以由应用级别返回，浏览器会直接跳转，API 几倍可以不考虑这两种情况。</p> <p>API 用到的 <code>3xx</code> 状态码，主要是 <code>303 See Other</code>，表示参考另一个 URL。它与 <code>302</code> 和 <code>307</code> 的含义一样，也是 “暂时重定向”，区别在于 <code>302</code> 和 <code>307</code> 用于 <code>GET</code> 请求，而 <code>303</code> 用于 <code>POST</code>、<code>PUT</code> 和 <code>DELETE</code> 请求。收到 <code>303</code> 之后，浏览器不会自动跳转，而会让用户决定下一步该怎么办。举个例子：</p> <div class="language-http extra-class"><pre class="language-http"><code><span class="token response-status">HTTP/1.1 <span class="token property">303 See Other</span></span>
<span class="token header-name keyword">Location:</span> /api/orders/12345
</code></pre></div><h3 id="_4-4xx-状态码"><a href="#_4-4xx-状态码" class="header-anchor">#</a> 4. <code>4xx</code> 状态码</h3> <p><code>4xx</code> 状态码表示客户端错误，主要有下面几种：</p> <ul><li>400：<code>Bad Requset</code> 服务器不理解客户端的请求，未做任何处理；</li> <li>401：<code>Unauthorized</code> 用户为提供身份验证凭据，或者没有通过身份验证；</li> <li>403：<code>Forbidden</code> 用户通过了验证，但是不具有访问资源所需的权限；</li> <li>404：<code>Not Found</code> 请求的资源不存在，或者不可用；</li> <li>405：用户已经通过了身份验证，但是所用的 HTTP 方法不在他的权限之内；</li> <li>410：<code>Gone</code> 所请求的资源已经从这个地址转移，不再可用；</li> <li>415：<code>Unsupported Media Type</code> 客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式；</li> <li>422：<code>Unprocessable Entity</code> 客户端上传的附件无法处理，导致请求失败；</li> <li>429：<code>Too Many Requests</code> 客户端的请求次数超过限额。</li></ul> <h3 id="_5-5xx-状态码"><a href="#_5-5xx-状态码" class="header-anchor">#</a> 5. <code>5xx</code> 状态码</h3> <p><code>5xx</code> 状态码表示服务端错误。一般来说，API 不会向用户透露服务器的详细信息，所以仅需要两个状态码就足够了：</p> <ul><li>500：<code>Internal Server Error</code> 客户端请求有效，服务器处理时发生了意外；</li> <li>503：<code>Service Unavailable</code> 服务器无法处理请求，一般用于网站维护状态。</li></ul> <h2 id="服务器响应"><a href="#服务器响应" class="header-anchor">#</a> 服务器响应</h2> <h3 id="_1-不要返回纯文本"><a href="#_1-不要返回纯文本" class="header-anchor">#</a> 1. 不要返回纯文本</h3> <p>API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回标准的结构化数据。所以服务器响应的 HTTP 头的 <code>Content-Type</code> 属性要设为 <code>application/json</code> 。</p> <h3 id="_2-发生错误时，不要返回-200-状态码"><a href="#_2-发生错误时，不要返回-200-状态码" class="header-anchor">#</a> 2. 发生错误时，不要返回 200 状态码</h3> <p>有一种不恰当的做法是，即使发生错误，也返回 200 状态码，把错误信息放在数据体中，例如：</p> <div class="language-http extra-class"><pre class="language-http"><code><span class="token response-status">HTTP/1.1 <span class="token property">200 OK</span></span>
<span class="token header-name keyword">Content-Type:</span> application/json<span class="token application-json">

<span class="token punctuation">{</span>
  <span class="token property">&quot;status&quot;</span><span class="token operator">:</span> <span class="token string">&quot;failure&quot;</span><span class="token punctuation">,</span>
  <span class="token property">&quot;data&quot;</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">&quot;error&quot;</span><span class="token operator">:</span> <span class="token string">&quot;Expected at least two items in list.&quot;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</span></code></pre></div><p>上面的代码中，解析数据体以后，才能得知操作失败。</p> <p>这样的做法实际上取消了状态码，这是完全不可取的。正确的做法是，状态码反应发生的错误，具体的错误信息放在数据体里面返回，举个例子：</p> <div class="language-http extra-class"><pre class="language-http"><code><span class="token response-status">HTTP/1.1 <span class="token property">400 Bad Request</span></span>
<span class="token header-name keyword">Content-Type:</span> application/json<span class="token application-json">

<span class="token punctuation">{</span>
  <span class="token property">&quot;error&quot;</span><span class="token operator">:</span> <span class="token string">&quot;Invalid payoad.&quot;</span><span class="token punctuation">,</span>
  <span class="token property">&quot;detail&quot;</span><span class="token operator">:</span> <span class="token punctuation">{</span>
     <span class="token property">&quot;surname&quot;</span><span class="token operator">:</span> <span class="token string">&quot;This field is required.&quot;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</span></code></pre></div><h2 id="参考资料"><a href="#参考资料" class="header-anchor">#</a> 参考资料</h2> <p><a href="http://www.ruanyifeng.com/blog/2011/09/restful.html" target="_blank" rel="noopener noreferrer">理解RESTful架构<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></p> <p><a href="http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html" target="_blank" rel="noopener noreferrer">RESTful API 最佳实践<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></p></div> <footer class="page-edit"><!----> <div class="last-updated"><span class="prefix">上次更新:</span> <span class="time">2020年3月17日星期二下午2点47分</span></div></footer> <div class="page-nav"><p class="inner"><span class="prev">
      ←
      <a href="/more/hodgepodge/mpv-keyboards.html" class="prev">
        mpv 快捷键
      </a></span> <span class="next"><a href="/more/hodgepodge/you-get.html">
        You Get
      </a>
      →
    </span></p></div> </main></div><div class="global-ui"><!----><!----></div></div>
    <script src="/assets/js/app.1f0f93c9.js" defer></script><script src="/assets/js/2.f28f3227.js" defer></script><script src="/assets/js/83.81ad8dbf.js" defer></script><script src="/assets/js/4.494c614b.js" defer></script><script src="/assets/js/3.a7eaa85f.js" defer></script>
  </body>
</html>
